<html lang="en"><head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <title>Connect Web Server</title>

	<script src="js/codemirror/codemirror.js"></script>
	<link rel="stylesheet" href="css/codemirror/codemirror.css">
	<script src="js/codemirror/mode/javascript.js"></script>
	<style>
		.CodeMirror { background: #f3f3f3; border:1px solid gray; font-size:1em; height:300px}
		.CodeMirror-scroll {height:100%; }
	</style>


    <!-- Framework CSS -->
    
    <link rel="stylesheet" href="css/blueprint/screen.css" type="text/css" media="screen, projection">
    <link rel="stylesheet" href="css/blueprint/print.css" type="text/css" media="print">
    <!--[if lt IE 8]><link rel="stylesheet" href="css/blueprint/ie.css" type="text/css" media="screen, projection"><![endif]-->

    <!-- Import fancy-type plugin for the sample page. -->
    <link rel="stylesheet" href="css/blueprint/fancytype.css" type="text/css" media="screen, projection">
    
    <!-- Custom styles to override framework -->
     <link rel="stylesheet" href="css/main.css" type="text/css" media="screen, projection">
  </head>
<body>
    <div class="container">
   
    
     <br/>
      <h1><a href="/"><img src="images/ConnectLogo.png"  alt="Connect" style="vertical-align:middle;" ></a>  Connect Web Server Reference</h1>
      
      <hr>
      <h2 class="alt"><a href="/">Home</a> | Scripting | <a href="freemarkerExtensions.html">Freemarker Extensions</a> | <a href="serverConfigGuide.html">Server Configuration</a></h2>
      <hr>
      
      <hr class="space">
      <div class="span-20 prepend-1">
       <h3>Basics</h3>
           <p>
              Connect uses javascript as the scripting language, processed through the <a href="https://developer.mozilla.org/en/docs/Rhino">Rhino</a> engine. Nothing to fancy here, its just Javascript that as a final step returns a value. It is important to note, this is server side JS, so you dont have the browser and DOM methods available to you.  </p>
       <p> A greate place to start learning about Javascript is the W3Schools Javascript tutorials (<a href="http://www.w3schools.com/js/" target="external">link</a>), and for reference books, you cant go past the O'reilly selection (<a href="http://oreilly.com/javascript/" target="external">link</a>).</p><br>
          
          <p> Once you have that under your belt, scripting on Connect is a 3 step process:</p>
          <ol>
       <li>Create your script file in the server script folder.</li>
       <li>Update the serverconfig.xml file with a link to your script</li>
       <li>Refresh the server to load the new configuration file, and the link to your script.</li>
              </ol>
       <p>And thats it ! Any further modifications to your script can be done directly on the source file, and the server will load and execute those modifications the next time the script is called.</p>
       <p>The server will take the last value generated by the script and return that as the response to the client that called the script. If you return a Javascript object, the server generates a JSON response (with appropiate content type specification) to the client.</p><br>
          
         <h5>Example - Simple function and logging</h5>
          
        <pre class="code">
        //My complicated number crunching function
        function add(a, b) {
            c = a + b;
            return c;
        }
        //Run it
        var result = add (10, 5);
        
        //Debug to server log
        log.debug('Result = ' + result);
        
        //Return the result
        result;
        </pre>
          <p> And thats it !!</p>
           <p> The little example above highlighted one extension to Rhino that Connect adds - that is the access to the logging framework to debug your code on the server. This is just the log4j "log" object that has been made available to the scripting engine. </p>
          
       <hr>
        <h3>Built in variables</h3>
        <p> Connect makes the following variables are available in the scripting environment: </p>
       <ul>
       <li>log - allows full access to the server log
       <li>request - provides access to the HTTP request that triggered the script
       <li>response - the server HTTP response
	   <li>data - access to the Connect datasources
	   <li>session - access to the current user session
		</ul>			
       <h5>Example - Accessing the HTTP Request</h5>
           <pre class="code">
        var result = "";
        for (i in request) { result += i + "\n"; }
        
        result
        </pre>
       <p> Processing a HTTP request is handled through the <b>request</b> variable that is available in the scripting environment. The best place to find out what you can do with the request is to look at the <b>WrappedRequest</b> class as this is code behind the request object accessible in the scripting engine. </p>
          
         
          
          
       
		<hr>
         <h3>DataSources</h3>
       <p> Accessing datasources, is a simple as requesting them by name, eg. </p>
       <pre>
       var ds = data.getDataSource("JDBCDataSource"); </pre>
       <p> Setting parameters is achieved as follows: </p>
       <pre>
       ds.setParam("region", "Western Europe"); </pre>
       
       <p> Putting it all together, with a function to list the results in a HTML table, we get:</p>
      <textarea id="code" name="code" style="display: none; ">
      
// Script example to access a data source      
      
function toTable(resultSet) {
	var buffer = "<table border=1>";
	for (var i=0; i< resultSet.size(); i++) {
		buffer += "<tr>";
		var record = resultSet.get(i);
		var keys = record.keys.toArray();
		if (i==0) {
			for (j in keys) {
				buffer += "<th>" + keys[j] + "</th>";
			}
			buffer +="</tr><tr>";
		}
		for (j in keys) {
			buffer += "<td>" + record.get(keys[j]) + "</td>";
		}
		buffer += "</tr>";
	}
	buffer += "</table>";
	return buffer;
}

var ds = data.getDataSource("JDBCDataSource");

ds.setParam("region", "Western Europe");

var result = ds.doQuery();

toTable(result)
       
       </textarea>
<script>
	//Initialise the editor
	var editor = CodeMirror.fromTextArea(document.getElementById("code"), {mode: "javascript", readOnly: true});
</script>
		<hr>
        <h3>Advanced</h3>
       <p> The server uses the Rhino (<a href="https://developer.mozilla.org/en/docs/Rhino" target="external">link</a>) javascript engine to process the scripts, hence all of the features of Rhino are available to developers. One cool feature, is that you can access Java classes directly from your script, eg:</p>
       <pre class="code">
       new java.util.Date()</pre>
      

       <p>Will generate:</p>
       <pre>
       Thu Jan 24 16:18:17 EST 2002</pre>
		
		<p>Another cool feature is being able to explore the methods and fields for an object, eg:</p>
		<pre class="code">
        var objectInfo = "";
        for (i in myObject) { objectInfo += i + "\n"; }
        objectInfo;</pre>
		<p>Note that not only the methods of the &quot;myObject&quot; class are listed, but also the methods inherited from the base class java.lang.Object (like wait). This makes it easier to work with objects in deeply nested inheritance hierarchies since you can see all the methods that are available for that object.

Rhino provides another convenience by allowing properties of JavaBeans to be accessed directly by their property names. A JavaBean property foo is defined by the methods getFoo and setFoo. Additionally, a boolean property of the same name can be defined by an isFoo method. So if you have a method called &quot;getParameterNames()&quot; in your java class, you will be able to access that method by either &quot;obj.parameterNames&quot; or &quot;obj.getParameterNames()&quot; in your script.</p>
		<p>The Rhino documentation also provides some performance hints to optimise the processing of your scripts (<a href="https://developer.mozilla.org/en-US/docs/Rhino/Performance" target="external">link</a>).</p>
		<p>&nbsp;</p>
		<h3>Viewing source</h3>
          <p> To view the source code of your script, simply append <b>?viewSource</b> to the script URL.</p>
        
        
      </div>
      <hr/>
          <div class="last quiet right"> 
          <a href="http://www.binarycube.com"><img src="images/logo-bw.png" width="150" /></a><br/>
      </div>
</div>
  

</body></html>